Amiga Plus 1999 #1/Amiga Plus 1999 #1.iso/System-Boost/Workbench/WindowToFront/DocsEnglish/WindowToFront.doc

Text File | 1998-06-17 | 25KB | 531 lines

                            WINDOWTOFRONT 1.6

           dedicated to the memory of Jay G. Miner (1932-1994)


   WARNING: WindowToFront requires AmigaOS Release 2 (or higher).


   INTRODUCTION

   WindowToFront is a commodity that was written to replace the original
"ClickToFront" program that comes with every Amiga.

   Why replace it? The main motivation was that I find really annoying the
way ClickToFront keeps bringing to front any Workbench window every time the
user double-clicks on an icon. This might still be tolerable with the volume
or drawer windows, but becomes inacceptable in the case of the main Workbench
window: when brought to front, it ends up covering almost the entire screen.
   Furthermore, I thought the program could use some additional features and
a real graphic user interface rather than having to be configured through its
icon Information window. So I wrote WindowToFront.

   WindowToFront allows to bring to front any non-backdrop window with a
chosen number of mouse clicks on it, and to send it to the background in
several ways; it's also possible to choose a different number of clicks for
three distinct window types, and even one for window borders.

   All the options are selectable with a control panel or by editing the tool
types; WindowToFront can be started from both Shell and Workbench, it can
save the preferred settings into its icon and it can be adapted to any
language by using the appropriate localization .catalog file.


   1. INSTALLATION

   The installation of WindowToFront is very simple: just run the supplied
script by double-clicking on the "Install" icon.

   However, if you prefer to install it by hand, all you have to do is to
copy the program along with its icon into your SYS:Tools/Commodities drawer,
and to add the following line to your User-startup script:

   Run > NIL: WindowToFront

   Alternatively you can simply put it into your WBStartup drawer.

   In addition, if you want to use WindowToFront in a language other than
english, you can localize it as explained in paragraph 6, "Localization".


   2. SHELL USAGE

   To find out the Shell template of WindowToFront, you can simply enter the
typical

   WindowToFront ?

   The template, anyway, is the following:

   CX_PRIORITY/N/K,CX_POPKEY/K,CX_POPUP/K,CLICKS/N/K,CLICKS_WB/N/K,
CLICKS_WBWIN/N/K,CLICKS_BORDER/N/K,CLICKS_BACK/N/K,QUALIFIER/K,
QUALIFIER_BACK/K,WBONLY/K,AUTOBACK/K,ACTIVATEBACK/K,HOTKEY_BACK/K,BACKMODE/K,
LANGUAGE/K,GADGETS/K,FORCETOPAZ/K:

   The keywords appearing here match exactly the tool types you can insert
in WindowToFront's icon. Let's see their meaning and default values:

   CX_PRIORITY=<num>           [default: 0]
   CX_POPKEY=<hotkey>          [default: CTRL w]
   CX_POPUP=<YES | NO>         [default: NO]

   These three are common to all Commodities programs. They allow to specify
the priority of WindowToFront compared to other Commodities (the default is
suggested), the key sequence that makes the control panel appear when it
is hidden, and whether the panel must pop up at the program's start or remain
hidden until called via the hotkey.

   CLICKS=<number of clicks>           [default: 2]

   This allows to choose the number of clicks that will be required to bring
to front a "normal" window, i. e. one that is neither the Workbench main
one nor that of a Workbench disk or drawer (in short, one that can't contain
Workbench icons).
   The selectable number of clicks varies from 1 to 4. Anyway, a single
click is strongly inadvisable, as it usually creates a lot of confusion.
   Specifying 0 as number of clicks disables this function.

   CLICKS_WB=<number of clicks>        [default: 3]

   This allows to choose the number of clicks to bring to front the main
window of the Workbench, that is, the one in which the disk icons appear.
This is possible only if the window wasn't made backdrop. You can safely
choose 2 for this option, as a double-click on a Workbench icon, if this
is of the DISK, DRAWER or TRASHCAN kind, does not bring the window to front.
   With other icon types (for instance AppIcons) in some cases it's still
possible that the window get brought to the front: if you find yourself
often in such a situation, you can for example set 3 as a value for this
parameter.
   Specifying 0 as number of clicks disables this function.

   CLICKS_WBWIN=<number of clicks>     [default: 2]

   With this you specify the number of clicks for Workbench windows
associated to a disk or to a drawer. These windows are usually smaller than
the entire screen, so normally it doesn't matter very much if one of them
get brought to front unintentionally by double-clicking on an icon that is
located inside it; anyway this won't happen in most cases (it certainly
won't happen if you double-click on a drawer or on the Trashcan).
   Specifying 0 as number of clicks disables this function.

   CLICKS_BORDER=<number of clicks>    [default: 2]

   This allows to specify the number of click to bring to front any window
when the mouse pointer is on its border or on its title bar (excluding the
system gadgets).
   Specifying 0 as number of clicks DOES NOT disables the function, but
means that the number of clicks to use for the border is the same defined
for the inside of the window (thus differentiating between the three window
types). Otherwise the number of clicks for the border is the same for all
window types.

   CLICKS_BACK=<number of clicks>      [default: 1]

   With this you specify the number of clicks that will be needed to send
to the background any window when you simultaneously press the key (or keys)
indicated with the QUALIFIER_BACK parameter (see below).
   This operation usually requires a qualifier, so there are no problems
with specifying 1 as number of clicks: in fact, it is the more convenient
choice.
   Specifying 0 as number of clicks disables this function.

   QUALIFIER=<qualifier>               [default: NONE]

   The qualifier is a key or combination of keys (for example, CTRL ALT) that
must be held pressed while clicking on windows to make the bring-to-front
function actually work.
   Because in most cases the need to press one or more keys together with
the mouse button slows down the operations (of the user, not of the
computer), it is advisable to specify NONE for this option.

   QUALIFIER_BACK=<qualifier>          [default: LALT]

   This qualifier, instead, is indispensable in order to be able to
distinguish between clicks made to bring a window to front and clicks made
to send it to the background.
   If both operations were to require the same qualifier and the same
number of clicks, the bring-to-front operation would always override the
other (it would be the only one to be executed).
   Note: until version 1.1 the program's behavior in this case was exactly
the opposite!
   If, on the other hand, you assign a different number of clicks to the two
operations, under the same qualifier the operation requiring less clicks
will be executed first. If you continue clicking with the mouse the other,
too, will then be executed.
   For instance, you can specify NONE for both qualifiers and assign 3 as
the number of clicks to send windows to back: by triple-clicking on a window,
it will be first brought to front, then immediately to back. This may be a
way to avoid using a qualifier, which may sometimes be uncomfortable.
   The default background qualifier is the left ALT key. I advise against
the use of the SHIFT keys, already handled by the Workbench, and of the
AMIGA keys, that have a special significance to Intuition. This means that
the keys more suitable to carry out this task are the two ALTs and CTRL.

   A note on the qualifiers: by specifying separately two analogous keys,
such as "LALT RALT", it will be required to SIMULTANEOUSLY press these
keys. By specifying instead only their common part, such as "ALT", it will
suffice to press any one of the two to perform the associated operation.
   Furthermore, the word NONE is valid no matter which language you localized
WindowToFront to, while its synonyms in other languages, as for instance
NESSUNO for italian, are only recognized if you use the relative catalog.
   See also paragraph 5 for a complete listing of the names suitable
as qualifiers.

   WBONLY=<YES | NO>                   [default: YES]

   By default, WindowToFront performs its function only with the windows
that appear on the Workbench screen (or on the default PUBLIC screen).
By specifying NO here you obtain that the program work on the windows of
all screens. Sometimes this might cause conflicts with the operations of the
program that opened these screens, but usually there are no particular
problems.
   Note: for this tool type and all others of the same type (YES/NO) any
specification different from "NO" (even a null string, such as "AUTOBACK="
or "WBONLY") will be interpreted as YES.

   AUTOBACK=<YES | NO>                 [default: NO]

   The specification of YES here means that if you use the number of clicks
chosen to bring a window to front on a window that is already in front of
all others (that is, it's not obscured by others) this window will be sent
to the background. If the window is instead partially obscured it will be
brought to front as usual.

   ACTIVATEBACK=<YES | NO>             [default: NO]

   Usually a window you send to the background is a window you don't want
to use for the moment, so there's no point at all in activating it. In fact
by default WindowToFront won't activate the windows you send to back in the
normal way (that is, with the combination QUALIFIER_BACK + CLICKS_BACK),
even if it will do so in the case of windows "sent away" with the AUTOBACK
method. By specifying YES here you will make WindowToFront always activate
the windows it sends to the background (although the reason of such a choice
would be completely beyond me...).

   HOTKEY_BACK=<hotkey>                [default: LALT ESC]

   With this keyword you specify the combination of keys which will cause
the current window to get sent to back. Which one is the current window
depends on the value you assign to the BACKMODE keyword.
   The default key combination is left ALT + ESC.

   BACKMODE=<POINTER | ACTIVE>         [default: POINTER]

   This keyword's purpose is to specify which window must be sent to back
when the key combination assigned to HOTKEY_BACK is pressed.
   By specifying POINTER the window under the mouse pointer will be sent
to back, while by specifying ACTIVE the sent-away window will be the active
one.

   LANGUAGE=<language>                 [default: locale]

   With this keyword you tell which language WindowToFront must use for its
localization (adaptation to a particular language).
   To make this possible, the appropriate .catalog file for that language
must be present in its directory, as it is explained more thoroughly in
paragraph 6, "Localization".
   It is not necessary to have the locale.library to make use of the
localization.

   GADGETS=<YES | NO>                  [default: NO]

   Lastly, with this option you can tell the program whether you want or not
WindowToFront's control panel have at its bottom the two "Hide" and "Quit"
gadgets.
   They aren't needed, as these two options are already present in the
"Project" menu and their elimination allows to save some space by having
a shorter window, but their presence could be a commodity some people just
can't do without.

   FORCETOPAZ=<YES | NO>               [default: NO]

   Beginning with version 1.2, WindowToFront exploits a font-sensitive
user interface (i. e. it adapts itself to the font used for the Workbench).
Those who should want, for some reasons, to continue using the topaz 8 font,
can do it by specifying YES as the value of this keyword.


   3. WORKBENCH USAGE

   The usage from Workbench is analogous to that of all other Commodities:
you just have to run the program by double-clicking on its icon.
   This operation will bring up the control panel if among the icon's tool
types there is "CX_POPUP=YES", otherwise the program will start running
"silently" in the background.
   To make the control panel appear you will then need to press the key
combination specified with the "CX_POPKEY" tool type (also in the icon).
   With the "Information..." item of the Workbench's "Icons" menu you can
add, delete and modify the tool types of the WindowToFront's icon.
   Alternatively, after you have modified the working parameters of
WindowToFront using the control panel, you can save these parameters into
the program's icon with the "Save" item of the "Project" menu. However
some parameters, as for instance "CX_POPUP", can't be modified this second
way.
   The tool types recognized by WindowToFront when started from Workbench,
as their possible values, are exactly the same described in the "Shell usage"
paragraph.
   By placing WindowToFront into the "WBStartup" drawer (with its icon) the
program will be launched automatically at every reboot. In this case you
need to have "DONOTWAIT" among the icon's tool types, as WindowToFront,
like any other standard Commodity, isn't self-detaching.


   4. THE CONTROL PANEL

   It wouldn't be really necessary to describe the usage of the control
panel, because it's very intuitive, however let's examine briefly the
various gadgets and menus. In referring to them I'll use their english name.

   "Hot Key:" - It allows to modify the hotkey (key combination) that is
needed to bring up the control panel. If you insert there an incorrect
expression the gadget's previous contents will be restored (after you
press RETURN). Warning: capital letters such as "W" imply a simultaneous
SHIFT key press.

   "About..." - It causes the appearance of a requester with some information
about the program and its author.

   "Normal Windows:" - This slider allows to change the number of clicks to
be used to bring to front "normal" windows (those not belonging to the
Workbench and not able to contain icons). The change takes place in real
time, that is, you don't need to close the control panel to make it work.

   "Main Workbench Window:" - As above, but for the main Workbench window,
the one which contains the icons for floppy disks, hard disk partitions,
Ram/Rad disks, and so on.

   "Workbench Windows:" - As above, but for any other window owned by the
Workbench (for example drawers).

   "Window Border:" - As above, but for the border of any window. By setting
this slider to "Off", you obtain that the number of clicks to use on the
border be the same you use inside the windows.

   "To Back:" - With this slider you specify the number of clicks to use
to send windows to the background (when you simultaneously also press the
qualifier associated to this operation).

   "Workbench Only:" - This checkbox allows you to choose whether
WindowToFront must operate on the windows of all screens or only on the
ones of the Workbench screen.

   "AutoBack:" - Checkbox to activate/deactivate the AUTOBACK facility (see
the "Shell usage" paragraph).

   "Activate Back:" - Checkbox to specify whether windows sent to the
background must be activated or not. This gadget will be disabled if the
number of clicks to send windows to back is 0 (Off) or if it's 1 and you
didn't specify any qualifier for the "send to back" operation.
   In the latter case it's in fact necessary to always activate the window
on which you click, or else no window will ever be able to be activated
(at least in the usual mode, using a single click without qualifiers).

   "To Front:" - This string gadget contains the qualifier for the "bring
window to front" operation. By inserting (with RETURN) an invalid qualifier,
the previous value will be restored.
   By inserting a null string it will be displayed NONE or the equivalent
term of the used language. It is possible to use directly that term or NONE
(always valid with any language) to specify that indeed it isn't required
any qualifier for the mentioned operation.

   "To Back:" - Exactly as above, but for the "send window to back"
operation. It is usually better not to insert NONE here.

   "Keys:" - This string gadget contains the combination of keys which will
trigger the "send window to back" action. If you insert an incorrect value
here followed by RETURN, the previous value will be restored.

   "Mode:" - This cycle gadget allows you to choose which window will be
sent to back when you press the key combination explained above. The "Under
Pointer" value means that the chosen window will be the one under the mouse
pointer, while the "Active Window" value means that the window sent to back
will be the active one.

   "Hide" - This gadget is present only if you specified the tool type
GADGETS=YES at the launch of WindowToFront (on the command line or in the
icon). Its purpose is to make the control panel disappear, while keeping
WindowToFront active in the background. You can achieve the same effect by
pressing the "H" key (or another key depending on the used language, as
specified in the .catalog file).
   To make the control panel show up again you must press the hotkey.

   "Quit" - This gadget is present only if you specified the tool type
GADGETS=YES at the launch of WindowToFront (on the command line or in the
icon). Its purpose is to terminate the execution of WindowToFront and to
remove it from memory. You can achieve the same effect by pressing the "Q"
key (or another key depending on the used language, as specified in the
.catalog file).

   "Save" (Project menu) - By selecting this menu item you save the current
settings (hotkey, number of clicks, options, qualifiers) into the icon of
WindowToFront. If the icon doesn't exist, the program creates it first.

   "Hide" (Project menu) - This menu item has the same function as the
"Hide" gadget (see).

   "Quit" (Project menu) - This menu item has the same function as the
"Quit" gadget (see).

   Lastly, it's worth remembering that the close gadget of the window of
WindowToFront has the same effect as the "Hide" menu item (or gadget).


   5. QUALIFIERS RECOGNIZED BY THE COMMODITIES.LIBRARY

   This is a listing of the qualifiers recognized by version 37 (and above)
of the commodities.library and usable with WindowToFront.

   QUALIFIER               MEANING

   LCOMMAND                Left AMIGA key
   RCOMMAND                Right AMIGA key
   LSHIFT                  Left SHIFT key
   RSHIFT                  Right SHIFT key
   LALT                    Left ALT key
   RALT                    Right ALT key
   CAPSLOCK                Caps Lock key
   CONTROL                 CTRL key
   SHIFT                   Any SHIFT key
   CAPS                    Any SHIFT key or Caps Lock
   ALT                     Any ALT key

   Note: starting with version 38 (OS 2.1) of the commodities.library there
are several synonyms for these qualifiers, but it's not necessary to list
them here. If you own the 2.1 or 3.x operating system you should find them
reported in the system software manual.


   6. LOCALIZATION

   By default WindowToFront communicates with the user in the english
language, but, of course, the program can be localized, i. e. adapted to
a specific language.

   Beginning with version 1.2, WindowToFront can only be localized with
the proper .catalog files containing its strings translated into various
languages. The program is able to interpret these files even if the
locale.library is not present, but in the future this support could be
removed because of its redundancy.

   If you did install WindowToFront using the supplied installation script,
you have probably already chosen your preferred language, and the appropriate
catalog should have already been copied to its correct location. If this is
not the case, or if you want to install more catalogs, here is how to do it.

   All you have to do is to copy the "windowtofront.catalog" file for your
language, if supplied, to the directory LOCALE:Catalogs/<langname>, where
<langname> is the name of your locale language. For example, if you are
italian, you could copy the file "Catalogs/italiano/windowtofront.catalog"
(found in WindowToFront's distribuction directory) to the directory
"LOCALE:Catalogs/italiano/" of your system, thus obtaining the localization
file "LOCALE:Catalogs/italiano/windowtofront.catalog".

   Even if you have the locale.library, you don't need to select your
preferred language with the Locale preferences editor: you can specify it
directly in WindowToFront by using the keyword (or tool type) LANGUAGE.
   If you want the program to use the locale language you chose with the
Locale editor, simply set the aforementioned keyword to "locale".

   Anyway, the size of the control panel and the position of the gadgets
will be adapted to the length of the used strings.

   With version 1.6 of WindowToFront I supplied officially the .catalog files
for the english and italian languages; in the future I'll manage to add other
ones (if someone writes them for me, that is).

   You can create a .catalog file for your language by using the program for
developers "CatComp" with the .cd file I supplied: if you are a developer you
should already know how to do it. Alternatively, you can use one of the many
PD programs that carry out this operation by modifying an already existing
.catalog file.

NOTE: If you put together versions for other languages of the .catalog file,
you're free (and welcome) to send them to me via electronic mail, so that I
be able to include them into a future WindowToFront distribution.
You can also spread them separately, of course always in the public domain.


   7. IMPORTANT NOTES

   WindowToFront does nothing when the user selects a gadget within a
window. Some programs handle privately a double click on their gadgets, so
WindowToFront should not interfere with them.
   Furthermore, WindowToFront doesn't bring to front backdrop windows.

   Generally, to specify only one click without any qualifier for any
operation causes confusion and serious troubles in the user's handling of
the windows as well as interaction problems between him and Intuition.
   It is recommended, therefore, NOT to do that.

   Starting with version 1.1 WindowToFront is able to save its settings even
if in its directory there isn't an icon named after it; in this case the
program will create a new icon for itself.

   Finally, for various reasons it would take too much time to explain, I
suggest you not to rename the program. Anyway "WindowToFront" is its
official name and so I intend it to be known by Amiga users worldwide (ok,
nobody does such things anymore, but still...).


   8. EXISTING REVISIONS

   1.6   Significantly reduced the stack usage; before it could cause crashes
         when playing with the GUI (thanks to Nils Görs for the report).
         Also, the executable is now 236 bytes shorter.

   1.5   Increased compatibility with DirOpus 5 when used as a Workbench
         replacement (still not perfect, though). Added an installation script
         to keep up with the times. Documentation rewritten in its most
         ancient parts. Recompiled using SAS/C 6.58. The executable is 88
         bytes shorter.

   1.4   Some more bugs fixed. Documentation partially rewritten (it was
         becoming obsolete). Even more optimized: now the executable is 1132
         bytes shorter.

   1.3   Removed some bugs that caused Enforcer hits. Executable 92 bytes
         shorter.
         [Note: this version can only be found on the IPISA '95 CD-ROM]

   1.2   Completely rewritten and optimized using SAS/C 6.51.
         Added the possibility of sending windows to back with a combination
         of keys (thanks to Federico Chiesa for the excellent suggestion).
         Now the control panel is completely font-sensitive. Under OS 3.0+
         the NewLook menus are used. Removed support of text file for the
         localization: only usage of .catalog files remains, however this
         doesn't require the locale.library. Slightly modified behavior in
         certain situations. Solved the icon double-click problem! Lastly,
         the executable is now 7228 bytes shorter.
         [Note: this version was only released to beta-testers]

   1.1   The localization now also supports the locale.library (and in
         the future it will support only that). The look of the panel is
         slightly better. Now WindowToFront is able to create its icon
         if this doesn't exist while saving the settings. Also added some
         error messages. The about requester is now an EasyRequester.
         Lastly, the executable is now 612 bytes shorter.

   1.0   The original version.


   9. FINAL NOTES

   If you discover bugs, have doubts or want to send me suggestions (always
welcome) for future versions of WindowToFront, write to:

      Massimo Tantignone
      Via Campagnoli, 4
      28100 NOVARA
      ITALY

      E-mail: [e-mail]


   And now for a traditional conclusion:

               //
   Thanks to \X/ AMIGA for STILL being the best computer ever!